Comprehensive investigation and design document covering:
- Full call graph from GoalSeekingAgent down to memory operations
- Evidence that LearningAgent bypasses AgenticLoop (self.loop never called)
- Corrected OODA loop with Memory.remember()/recall() at every phase
- Unification design merging LearningAgent and GoalSeekingAgent
- Eval compatibility analysis (zero harness changes needed)
- Ordered 6-phase implementation plan with risk assessments
- Three Mermaid diagrams: current call graph, proposed OODA loop, unification architecture

Investigation only — no code changes to agent files.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Workstream 1 — semantic routing in dht.py:
- ShardStore: add _summary_embedding (numpy running average), _embedding_count,
  _embedding_generator; set_embedding_generator() method; store() computes
  running-average embedding on each fact stored when generator is available
- DHTRouter.set_embedding_generator(): propagates to all existing shards
- DHTRouter.add_agent(): sets embedding generator on new shards
- DHTRouter.store_fact(): ensures embedding_generator propagated to shard
- DHTRouter._select_query_targets(): semantic routing via cosine similarity
  when embeddings exist; falls back to keyword routing otherwise

Workstream 2 — Memory facade wired into OODA loop:
- AgenticLoop.__init__: accepts optional memory (Memory facade instance)
- AgenticLoop.observe(): OBSERVE phase — remember() + recall() via Memory facade
- AgenticLoop.orient(): ORIENT phase — recall domain knowledge, build world model
- AgenticLoop.perceive(): internally calls observe()+orient(); falls back to
  memory_retriever keyword search when no Memory facade configured
- AgenticLoop.learn(): uses memory.remember(outcome_summary) when facade set;
  falls back to memory_retriever.store_fact() otherwise
- LearningAgent.learn_from_content(): calls self.loop.observe() before fact
  extraction (OBSERVE) and self.loop.learn() after (LEARN)
- LearningAgent.answer_question(): structured around OODA loop via comments;
  OBSERVE at entry, existing retrieval IS the ORIENT phase, DECIDE is synthesis,
  ACT records Q&A pair; public signatures unchanged

All 74 tests pass (test_distributed_hive + test_memory_facade).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Covers OODA loop, cognitive memory model (6 types), DHT distributed
topology, semantic routing, Memory facade, eval harness, and file map.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…buted backends

Implements a pluggable graph persistence layer that abstracts CognitiveMemory
from its storage backend.

- graph_store.py: @runtime_checkable Protocol with 12 methods and 6 cognitive
  memory schema constants (SEMANTIC, EPISODIC, PROCEDURAL, WORKING, STRATEGIC, SOCIAL)
- memory_store.py: InMemoryGraphStore — dict-based, thread-safe, keyword search
- kuzu_store.py: KuzuGraphStore — wraps kuzu.Database with Cypher CREATE/MATCH queries
- distributed_store.py: DistributedGraphStore — DHT ring sharding via HashRing,
  replication factor, semantic routing, and bloom-filter gossip
- memory/__init__.py: exports all four classes
- facade.py: Memory.graph_store property; constructs correct backend by topology+backend
- tests/test_graph_store.py: 19 tests (8 parameterized × 2 backends + 3 distributed)

All 19 tests pass: uv run pytest tests/test_graph_store.py -v

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Add shard_backend field to MemoryConfig with AMPLIHACK_MEMORY_SHARD_BACKEND env var
- DistributedGraphStore accepts shard_backend, storage_path, kuzu_buffer_pool_mb params
- add_agent() creates KuzuGraphStore or InMemoryGraphStore based on shard_backend;
  shard_factory takes precedence when provided
- facade.py passes shard_backend and storage_path from MemoryConfig to DistributedGraphStore
- docs: add shard_backend config example and kuzu vs memory guidance
- tests: add test_distributed_with_kuzu_shards verifying persistence across store reopen

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- InMemoryGraphStore: add get_all_node_ids, export_nodes, export_edges,
  import_nodes, import_edges for shard exchange
- KuzuGraphStore: same 5 methods using Cypher queries; fix direction='in'
  edge query to return canonical from_id/to_id
- GraphStore Protocol: declare all 5 new methods
- DistributedGraphStore: rewrite run_gossip_round() to exchange full node
  data via bloom filter gossip; add rebuild_shard() to pull peer data via
  DHT ring; update add_agent() to call rebuild_shard() when peers have data
- Tests: add test_export_import_nodes, test_export_import_edges,
  test_gossip_full_nodes, test_gossip_edges, test_rebuild_on_join (all pass)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- FIX 1: export_edges() filters structural keys correctly from properties
- FIX 2: retract_fact() returns bool; ShardStore.search() skips retracted facts
- FIX 3: _node_content_keys map stored at create_node time; rebuild_shard uses correct routing key
- FIX 4: _validate_identifier() guards all f-string interpolations in kuzu_store.py
- FIX 5: Silent except:pass replaced with ImportError + Exception + logging in dht.py/distributed_store.py
- FIX 6: get_summary_embedding() method added to ShardStore and _AgentShard with lock; call sites updated
- FIX 8: route_query() returns list[str] agent_id strings instead of HiveAgent objects
- FIX 9: escalate_fact() and broadcast_fact() added to DistributedHiveGraph
- FIX 10: _query_targets returns all_ids[:_query_fanout] instead of *3 over-fetch
- FIX 11: int() parsing of env vars in config.py wrapped in try/except ValueError with logging
- FIX 12: Dead code (col_names/param_refs/overwritten query) removed from kuzu_store.py
- FIX 13: export_edges returns 6-tuples (rel_type, from_table, from_id, to_table, to_id, props); import_edges accepts them
- Updated test_graph_store.py assertions to match new 6-tuple edge format

All 103 tests pass.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…replication

- NetworkGraphStore wraps a local GraphStore and replicates create_node/create_edge
  over a network transport (local/redis/azure_service_bus) using existing event_bus.py
- Background thread processes incoming events: applies remote writes and responds to
  distributed search queries
- search_nodes publishes SEARCH_QUERY, collects remote responses within timeout,
  and returns merged/deduplicated results
- AMPLIHACK_MEMORY_TRANSPORT and AMPLIHACK_MEMORY_CONNECTION_STRING env vars added to
  MemoryConfig and Memory facade; non-local transport auto-wraps store with NetworkGraphStore
- 20 unit tests all passing

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- src/amplihack/cli/hive.py: argparse-based CLI with create, add-agent, start,
  status, stop commands
- create: scaffolds ~/.amplihack/hives/NAME/config.yaml with N agents
- add-agent: appends agent entry with name, prompt, optional kuzu_db path
- start --target local: launches agents as subprocesses with correct env vars;
  --target azure delegates to deploy/azure_hive/deploy.sh
- status: shows agent PID status table with running/stopped states
- stop: sends SIGTERM to all running agent processes
- Hive config YAML matches spec (name, transport, connection_string, agents list)
- Registered amplihack-hive = amplihack.cli.hive:main in pyproject.toml
- 21 unit tests all passing

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

deploy/azure_hive/ contains:
- Dockerfile: python:3.11-slim base, installs amplihack + kuzu + sentence-transformers,
  non-root user (amplihack-agent), entrypoint=agent_entrypoint.py
- deploy.sh: az CLI script to provision Service Bus namespace+topic+subscriptions,
  ACR, Azure File Share, and deploy N Container Apps (5 agents per app via Bicep)
  Supports --build-only, --infra-only, --cleanup, --status modes
- main.bicep: defines Container Apps Environment, Service Bus, File Share,
  Container Registry, and N Container App resources with per-agent env vars
- agent_entrypoint.py: reads AMPLIHACK_AGENT_NAME, AMPLIHACK_AGENT_PROMPT,
  AMPLIHACK_MEMORY_CONNECTION_STRING; creates Memory with NetworkGraphStore;
  runs OODA loop with graceful shutdown
- 27 unit tests all passing

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…d with deployment instructions

- agent_memory_architecture.md: add NetworkGraphStore section covering architecture,
  configuration, environment variables, and integration with Memory facade
- distributed_hive_mind.md: add comprehensive deployment guide covering local
  subprocess deployment, Azure Service Bus transport, and Azure Container Apps
  deployment with deploy.sh / main.bicep; includes troubleshooting section

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Remove hard docker requirement and add conditional: use local docker if available,
fall back to az acr build for environments without Docker daemon.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Covers goal-seeking agents, cognitive memory model, GraphStore protocol,
DHT architecture, eval results (94.1% single vs 45.8% federated),
Azure deployment, and next steps.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

COPY path must be relative to REPO_ROOT when using ACR remote build
with repo root as the build context.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Bicep does not support ceil() or float() functions. Use the equivalent
integer arithmetic formula (a + b - 1) / b for ceiling division.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Azure policy 'Storage account public access should be disallowed' requires
allowBlobPublicAccess: false on all storage accounts.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Without this, Container Apps may deploy before the ManagedEnvironment
storage mount is registered, causing ManagedEnvironmentStorageNotFound.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…f 'store'

The LLM intent detector was being called on non-question content, and
simple_recall (its default) was in ANSWER_INTENTS, causing everything
to be classified as answer. Content with no question mark or
interrogative prefix should always be stored, not answered.

Result: facts now stored correctly, recall works end-to-end.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…ination brick

Identifies and fills the architectural gap in the distributed hive mind: a
coordination layer that routes fact operations through Storage (HiveGraph),
Transport (EventBus), Discovery (Gossip), and Query (dedup+rerank) layers
based on a pluggable PromotionPolicy.

Changes:
- Add hive_mind/orchestrator.py: HiveMindOrchestrator + PromotionPolicy protocol
  + DefaultPromotionPolicy (threshold-based, uses constants, no magic numbers)
- Update hive_mind/__init__.py: export new classes with graceful try/except
- Add tests/hive_mind/test_orchestrator.py: 29 contract tests, all passing
- Add docs/hive_mind/MODULE_CREATION_GUIDE.md: explains the gap-identification
  and brick-creation process for future contributors

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…torial

Update Key Files table in ARCHITECTURE.md and add Step 3b tutorial
in GETTING_STARTED.md showing unified orchestration usage.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

All 15 experiment eval scripts import UnifiedHiveMind, HiveMindAgent,
and HiveMindConfig from hive_mind.unified which was removed during the
orchestrator refactor. This creates a new unified.py that wraps the
current four-layer architecture (InMemoryHiveGraph, LocalEventBus,
HiveMindOrchestrator) with the old API.

Includes consensus voting support (_HiveGraphWithConsensus) needed by
the 20-agent adversarial eval. All 4 hypotheses pass:
- H1: Hive >= 80% of Single (PASS)
- H2: Hive > Flat (+5.4%, PASS)
- H3: 10/10 adversarial facts blocked (PASS)
- H4: Hive > Isolated (+19.4%, PASS)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Three bugs prevented the distributed eval from finding agent answers:

1. Column index: Reader accessed row[0] (TenantId) instead of Log_s.
   Fixed by adding `| project Log_s` to the KQL query.

2. Question hint filter: Reader searched for question text inside answers,
   but agents write only the answer (not the question). Removed hint filter
   and search for any recent ANSWER line instead.

3. Python 3.13 escape: `!has` in KQL strings caused `\!has` due to
   Python 3.13's strict escape sequence handling. Moved the "internal
   error" filter to Python-side instead.

Also: Use AzureCliCredential instead of DefaultAzureCredential for
Log Analytics access, and widen lookback to 10 minutes for LA ingestion lag.

Result: Distributed eval now scores 22.3% (up from 0%). Remaining gap
vs single-agent (97%) is due to rate limiting across 100 agents and
answer-question correlation in the broadcast eval design.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add reference to https://rysweet.github.io/amplihack-agent-eval/ for
complete eval instructions. Note retry backoff in agent capabilities.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Topic name is now 'hive-events-<hiveName>' instead of the shared
'hive-events'. This prevents cross-talk between deployments sharing
a Service Bus namespace. The topic name is passed to agents via
AMPLIHACK_SB_TOPIC env var and output from the Bicep template.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Deploy now retries up to 3 times (HIVE_DEPLOY_RETRIES) with exponential
backoff (30s, 60s, 120s) on transient Azure errors like
ManagedEnvironmentProvisioningError. After exhausting retries in the
primary region, falls back to HIVE_FALLBACK_REGIONS (default:
eastus,westus3,centralus) and retries each.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- unified.py: Replace dead `if False else 0` with tracked event counter,
  fix stale peer lists (update all orchestrators on new agent registration)
- learning_agent.py: Extract 3 copy-pasted retry blocks into single
  _llm_completion_with_retry() method (DRY, single point of maintenance)
- deploy.sh: Clean up partial Container Apps Environment on region
  fallback before retrying in next region

Review: philosophy-guardian (CONDITIONAL PASS -> PASS), reviewer (11 issues,
4 blocking fixed, 7 deferred as low-priority/separate-PR)

311/312 tests pass (1 pre-existing failure unrelated to this branch).
20-agent eval: all 4 hypotheses PASS, 94.0% overall.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…th single-agent (#3006)

Add EVAL_QUESTIONS event handler to agent entrypoint that calls
agent.answer_question() directly — identical code path to single-agent
eval. Bypasses the OODA decide() path and Log Analytics polling that
caused the 11-35% vs 97% eval gap.

Architecture:
- Eval harness generates questions (same as single-agent)
- Distributes questions round-robin across agents via Service Bus
- Each agent calls answer_question() locally (injection layer, not OODA)
- Answers published to eval-responses topic with correlation IDs
- Eval harness collects, grades with same hybrid grader, same report format

New files:
- deploy/azure_hive/eval_distributed.py: distributed eval harness
- deploy/azure_hive/agent_entrypoint.py: EVAL_QUESTIONS handler
- deploy/azure_hive/main.bicep: eval-responses topic + subscription

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Reverts the EVAL_QUESTIONS handler that called answer_question() directly.
The OODA loop IS the agent — bypassing it tests a different code path
than what runs in production.

New approach uses DI/aspects:
- AnswerPublisher: stdout wrapper that intercepts ANSWER lines and
  publishes to eval-responses Service Bus topic with event_id correlation.
  Agent code is unchanged — it prints to stdout as normal.
- _CorrelatingInputSource: InputSource wrapper that reads event_id from
  incoming Service Bus messages and sets it on the AnswerPublisher before
  the agent's process() call. The OODA loop sees a normal InputSource.
- ServiceBusInputSource.last_event_metadata: exposes event_id, event_type,
  question_id from the most recently received message.
- eval_distributed.py: sends questions as regular INPUT events (not
  EVAL_QUESTIONS batches) so they go through the full OODA pipeline.

The agent's OODA loop (observe→orient→decide→act) is identical in
single-agent and distributed modes. All distribution happens via
injection at the entrypoint layer.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add RemoteAgentAdapter that implements the same interface as LearningAgent
(learn_from_content, answer_question, get_memory_stats, close). This lets
LongHorizonMemoryEval.run() use the EXACT same code path for distributed
eval as single-agent — same question generation, same grading, same report.

- learn_from_content(): sends LEARN_CONTENT via Service Bus (broadcast)
- answer_question(): sends INPUT event with event_id, blocks waiting for
  EVAL_ANSWER on response topic (correlated by event_id)
- Background listener thread collects answers from eval-responses topic
- Round-robin question distribution across N agents

Rewrite eval_distributed.py to use RemoteAgentAdapter + LongHorizonMemoryEval
instead of custom eval logic. The distributed eval is now:
  adapter = RemoteAgentAdapter(sb_conn, topic, response_topic)
  report = LongHorizonMemoryEval(turns, questions).run(adapter, grader_model)

Verified: 94% score with adapter pattern (local integration test, 50t/10q).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The AnswerPublisher stdout wrapper approach was fragile — stdout
interception doesn't reliably capture print() calls in all environments.
Switch to polling Log Analytics for ANSWER lines from the target agent,
which is proven to work (agents write to stdout → Container Apps → LA).

The adapter now takes workspace_id instead of response_topic. Each
answer_question() call sends the INPUT event, then polls LA for the
[agent-N] ANSWER: line from the target agent. eval_distributed.py
auto-detects the workspace ID if not provided.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

On the first answer_question() call, poll LA until agent LLM activity
drops to near-zero (5 consecutive low-activity checks). This ensures
agents have finished processing content before questions are sent.

Without this, questions arrive while agents are still processing content
and get queued behind hundreds of unprocessed turns, causing timeouts.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>